This looks good. It won't remove files, and will keep growing the deploy repo (on our other docs deploys we keep only one commit, i.e. force a single commit with just the latest content); but that is probably not a concern, at least for now.

Deployment is automatic via Travis it looks like; in terms of guarding against accidental deploys, are you thinking of switching back to manual deploys?

This looks good. It won't remove files, and will keep growing the deploy repo (on our other docs deploys we keep only one commit, i.e. force a single commit with just the latest content); but that is probably not a concern, at least for now.

I thought about it and prefer to keep history, may help with debugging, easier to go back in case of issues, and we can always clean up if size becomes a problem at some point (not expected any time soon).

Deployment is automatic via Travis it looks like; in terms of guarding against accidental deploys, are you thinking of switching back to manual deploys?

It's still manual, TravisCI doesn't run the deploy.sh script I added here - it only checks that the site builds. I think we should keep it that way for a while. Also allows accumulating a set of fixes and deploying once.

👍

I'm already seeing the submodule thing is going to be annoying, I'll change it to something else. Let's not merge this. I'll keep rebasing for a little while for deploys we need until I get to a better solution for this.

We could fairly easily update the NumPy docs uploader script to not overwrite the last commit.

I think the simplest option would be to

• limit merges to master to content that is ready for deploy
• add the public directory to the repo here
• make html is part of the workflow, perhaps add a CI check that the content of public is consistent with the version/installation of hugo recommended in the instructions.
• point numpy.org to the public directory.

Advantages:

• no separate repo needed
• workflow is greatly simplified.

Disadvantages:

• inadvertent merges to master are immediately deployed, so maybe institute a "two-reviewer" policy for merging to master and lock the branch for direct pushes.
• In some sense, this repo may grow larger since each merge commits another version of the public content where, theoretically, the separate repo could be rewriting history to make the repo smaller. I think we can revisit this if the repo grows to take too long to clone/update at some point in the future.

It is not clear to me how a manual process of

• running a make step
• committing the public content to a separate repo
• pushing that repo

is safer: in any case after a while the steps become force-of-habit and will be executed with the same level of caution as pushing the merge button here. In both cases, a change can be reverted by backing out the action.

Thanks for looking into this @mattip. I'm fine with keeping it in this repo, if so then it should be in the gh-pages branch though. Serving from a subfolder in master, if it's even possible, will make clones much slower and make it harder to rewrite history (easy to do if on a separate branch, if repo size grows too fast we'll just squash older commits).

I cannot remember why we have a separate repo now rather than gh-pages. Maybe has something to do with Cloudflare? @stefanv any thoughts?

The documentation for git clone says it will clone all remote tracking branches by default, so to save cloning the gh-pages branch you would have to specify --single-branch. Another option may be to recommend cloning only part of the history via `--shallow-since or one of the other strategies to minimize history, that could be part of the tag line at the top of the repo description.

The comment about rewriting history makes sense, even though this repo is only 20MB right now it could grow as time goes on. So I would be in favor of having a gh-pages branch. I think in order to use github pages (see step 4) you can only specify / or /docs to serve from, so the build should point hugo to create the pages in /docs

see step 4) you can only specify / or /docs to serve from, so the build should point hugo to create the pages in /docs

Why not /? That's the regular way of using gh-pages. There's nothing else that should be in that branch, only the generated pages.

Ahh, I see you are talking about this workflow. Should I do a PR to add that deploy script to the Makefile?

That would be great, thanks Matti.

Same repo is fine; here is an example of that:

https://github.com/skyportal/skyportal/blob/master/.github/workflows/build-and-deploy-docs.yaml#L63

@stefanv that seems to be running on repo skyportal/skyportal and publishing to skyportal/docs

I spent some time on the idea of having public be a worktree branch as in the recommended workflow above. It does these steps:

• deletes the public directory
• creates a gh-pages branch as a worktree in the public directory
• rebuilds the documentation
• commits the documentation
• now there is a worktree branch gh-pages with just the built documentation.
• pushes that branch to the original repo

Are we comfortable with building the documentation once, verifying the build, then building it again (hopefully with the same build arguments) and deploying the second build? I think a workflow like this makes more sense, since we are working with a Makefile anyway

• make clean will delete the public directory and delete the worktree branch in public
• make html will create the worktree branch in public if it does not exist and build the documentation
• make deploy will commit and push the worktree branch`

Thanks @mattip, those steps sound reasonable.

Are we comfortable with building the documentation once, verifying the build, then building it again (hopefully with the same build arguments) and deploying the second build?

Assuming you mean the Netlify preview with the first build, yes. There are no build arguments, the whole command is simply hugo. I wouldn't bother with a Makefile. Just use rm -rf public/ to clean, and hugo to rebuild.

Superceded by gh-353, so closing.